“Netrc” files are a de facto standard. They look like this:
machine mymachine login myloginname password mypassword port myport
The machine is the server (either a DNS name or an IP address).
The port is optional. If it's missing, auth-source will assume any port is OK. Actually the port is a protocol name or a port number so you can have separate entries for port 143 and for protocol imap if you fancy that. Anyway, you can just omit the port if you don't need it.
The login and password are simply your login credentials to the server.
“Netrc” files are usually called
.authinfo or .netrc; nowadays
.authinfo seems to be more popular and the
auth-source library encourages this confusion by making it the
default, as you'll see later.
If you have problems with the port, set
auth-source-debug to t and see what
port the library is checking in the *Messages*
buffer. Ditto for any other problems, your first step is always
to see what's being checked. The second step, of course, is to
write a blog entry about it and wait for the answer in the
comments.
You can customize the variable auth-sources. The
following may be needed if you are using an older version of
Emacs or if the auth-source library is not loaded for some other
reason.
(require 'auth-source) ;; probably not necessary
(customize-variable 'auth-sources) ;; optional, do it once
The
auth-sourcesvariable tells the auth-source library where your netrc files or Secret Service API collection items live for a particular host and protocol. While you can get fancy, the default and simplest configuration is:;;; old default: required :host and :protocol, not needed anymore (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) ;;; mostly equivalent (see below about fallbacks) but shorter: (setq auth-sources '((:source "~/.authinfo.gpg")))This says “for any host and any protocol, use just that one file.” Sweet simplicity. In fact, the latter is already the default, so unless you want to move your netrc file, it will just work if you have that file. Make sure it exists.
By adding multiple entries to
auth-sourceswith a particular host or protocol, you can have specific netrc files for that host or protocol. Usually this is unnecessary but may make sense if you have shared netrc files or some other unusual setup (90% of Emacs users have unusual setups and the remaining 10% are really unusual).Here's an example that uses the Secret Service API for all lookups, using the default collection:
(setq auth-sources '((:source (:secrets default))))And here's a mixed example, using two sources:
(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") (:source "~/.authinfo.gpg")))The best match is determined by order (starts from the bottom) only for the first pass, where things are checked exactly. In the example above, the first pass would find a single match for host
myserver. The netrc choice would fail because it matches any host and protocol implicitly (as a fallback). A specified value of:host tinauth-sourcesis considered a match on the first pass, unlike a missing:host.Now if you look for host
missing, it won't match either source explicitly. The second pass (the fallback pass) will look at all the implicit matches and collect them. They will be scored and returned sorted by score. The score is based on the number of explicit parameters that matched. See theauth-pickfunction for details.
If you don't customize auth-sources, you'll have
to live with the defaults: any host and any port are looked up in
the netrc file ~/.authinfo.gpg, which is a GnuPG
encrypted file (see
GnuPG and EasyPG Assistant Configuration).
The simplest working netrc line example is one without a port.
machine YOURMACHINE login YOU password YOURPASSWORD
This will match any authentication port. Simple, right? But what if there's a SMTP server on port 433 of that machine that needs a different password from the IMAP server?
machine YOURMACHINE login YOU password SMTPPASSWORD port 433
machine YOURMACHINE login YOU password GENERALPASSWORD
For url-auth authentication (HTTP/HTTPS), you need to put this in your netrc file:
machine yourmachine.com:80 port http login testuser password testpass
This will match any realm and authentication method (basic or digest) over HTTP. HTTPS is set up similarly. If you want finer controls, explore the url-auth source code and variables.
For Tramp authentication, use:
machine yourmachine.com port scp login testuser password testpass
Note that the port denotes the Tramp connection method. When you don't use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup.